This document lists/explains configuration and metadata for Sugar Cake (SCake) animations. Not all parameters are required, but filling them in is recommended.

: DISCLAIMER :
	Project Sugar Cake is incomplete, these are just the currently PLANNED systems and are not all currently in and functional. Please have patience as systems are integrated over time.

	This document makes the system 'look' really complex, but really to get an animation going you just need a single animation montage within UE5 and you can set up an animation event, however for the optimal experience you'll want at least 1 preclimax animation, 1 climax, and 1 postclimax animation. (If you lack any of these, you can just set the same animation for each stage)

[> Systems Explainer <]
	Project Sugar Cake features a highly customizable animation system for both animators and users with the goal of allowing animators to take advantage of the full animation montage system in UE5 while still integrating with the game and allowing users to customize and create their own animation events. To better understand the systems let's go over how SCake works. SCake uses what I call "Animation Events", these events consist of various individual animations stringed together in 'stages' with metadata both specific to each animation as well as the animation event as a whole. Each individual animation is registered into SCake, then Animation Events can be configured to use any animation. Animators are encouraged to create their own Animation Events that act as a full scene, but this is not required since users will be able to configure those animations into their own events as they desire. Players can also choose to manually play through Animation Events and select animations they like.

	'Paths' are critical to the dynamic systems of Animation Events. Erotic animations play through on 3 paths that are configured dynamically. The first path is the 'normal' path, this is the main animation's playtime without any climax. Non-Erotic animations will always use this first path exclusively and assume no climax. The second path is the climax path, this consists of animations both for climax animations with a limited number of climaxing actors as well as in-sync climax animations when all actors are at climax. If not all actors have climaxed after the animations on the second path has finished then it transitions back to the first path, but if all actors have climaxed then it transitions to the final path. This third path is a short post-climax animation used as a 'finishing touches' style animation. (Additionally what triggers this post-climax animation can be configured by the framework, such as entering only after all actors climax, or only after all included males climax, ect.)

	Path Examples with 2 actors...
		Standard Synced Climax Animation
		'PreClimax'	  : - - - - - - |
		'Actor1Climax':
		'Actor2Climax':
		'SyncedClimax':             | - |
		'Post Climax' :                 | - END
		
		Individual Climax Animation where Actor 2 orgasms first
		'PreClimax'	  : - - |   | - |
		'Actor1Climax':             | - |
		'Actor2Climax':     | - |
		'SyncedClimax':
		'Post Climax' :                 | - END
		
		Individual Climax Animation where Actor 1 orgasms but Actor 2 does not
		'PreClimax'	  : - - - - |   | - - - END
		'Actor1Climax':         | - |
		'Actor2Climax':
		'SyncedClimax':
		'Post Climax' :
		
		No Climax or Non-Erotic Animation
		'PreClimax'	  : - - - - - - - - - - END
		'Actor1Climax':
		'Actor2Climax':
		'SyncedClimax':
		'Post Climax' :

	These examples assume automatic (or at least linearly played) animations with a fixed end time, however users can change how events play out or choose to play individual animations with switching to climax animations automatically or by the user's input.

	All this sounds great, however not all animation packs will feature the full set of animations available, so some 'orgasm effects' may be applied instead depending on how each Animation Event is configured. Some strangeness can also occur if climax animations are not in sync with the animation it is transitioning from, such as switching from doggy style to missionary style, some care should be taken when configuring animations. Also, certain fetishes may not fit into this mold. In these cases where the system doesn't fit your needs you can create custom events using UE5 Anim Montages with SCake Module integration for the desired effect, animations can even store arbitrary string data to reference (This data is stored as a TMap|Name|String, use Name to reference).

[> Physical Gender/Sex Assignment <]
	For the sake of simplicity, 'Gender/Sex' definitions are entirely determined by the 'equipment' of the body and have nothing to do with identity. Currently (at the time of writing) the base game only supports Male and Female, however SCake defines bodies as having certain physical sex organs, such as vagina, penis, breasts, penis+vagina, anus, ect. Users will be able to configure what each Pal Type has so it can match their customized game properly.

[> Additional Notes <]
	- Proper initial configuration is important, if you're an animator and struggling to configure your animations please contact me or post over on our Discord for help and we can get things rolling! ^-^
	- Although the framework will support automatic sound configurations, custom sounds can be played through the Anim Montage system itself. (Call the SCake Event to play built-in animation sounds)
	- External objects (furniture) can be defined, but are not required.
	- 'Equips' (like toys) is supported by the framework but can also be applied through Anim Montages and Modules

[> Limitations <]
	- Gender assignment is limited to male / female within the game, an additional framework would be required to change this and support more. Manual option to allow one to act as the other will be available.
	- If an Anim Montage has invalid metadata then it can't be registered for use in the framework. Most options will have defaults to fall back on but requirements must be filled.
	- If an Animation Event features an invalid animation it won't be registered or usable, all animations must have valid data and align with all animations in the event.
	- Animations can only be initially registered by path, this is because there's no way to ensure any other variables will initiate before registration. Within the UI users can still select by name, but these will only show after animations have been registered.

IMPORTANT NOTE :
	It is important to configure animations and these parameters correctly to provide users the best experience. It's worth learning some of UE5's animation montage features before you begin animating to better understand how these systems can be used.

User Configuration :
	Users will be able to change all animation configurations or even blend stages from different animations together to create their own animation events. This means if something isn't working correctly, this can be adjusted by the user.

-- -- --

[> Key-Terms <]
	SCake_
		Prefix applied to callable Sugar Cake functions, makes them easier to find in the BP system.
	Animation
		Animation refers to a single set of animations all characters in a scene will play in-sync with eachother
	Animation Event
		Animation Event refers to all Stages of a partiular event
	Stage
		Animation Events are divided into 'stages' where each stage has its own designated animation. Animators/Users can define how each stage behaves and how long each stage is expected to last. By default stages progress linearly and automatically but users can choose to manually progress stages.
	Climax
		Climax refers to an orgasm animation.

-- -- --

[> Animation Parameters <]

	Notes :
		- When registering animations, register normal animations and then link climax animations. If you have multiple climax animations for a single normal animation you can register an animation with different climax variants and register it as a new animation with a new unique AnimID.
		- Currently there is no sound implementation for the framework, so sounds must be done manually through the Animation Montages themselves. In the future custom sound events and options may be added.
	
	~ Parameters for JSON ~
	RegisterAnim
		RegisterAnim denotes you want to register animations, you can include multiple animations by defining a new value set to start a new tree, follow this format exactly even if you're only registering a single animation. I recommend using incrementing numberes like 0, 1, 2, ect to keep arrays in the expected order, however I added 'Anim' here for readability and will do so a few times here where it isn't crucial what order they are in.
	RegisterEvent
		Just like with RegisterAnim, RegisterEvent is used to define registering events, similar format but has different parameters.

	~ Parameters for Animations ~
	UniqueAnimID
		[Required] The UniqueID is used to find this registered animation, referenced in Events and used for playback. If another animation has the same uniqueID they will overwrite one another. If you'd like to overwrite another animation's data without removing them from the register use a higher AnimVersion to overwrite that animation with your new revised version.
	AnimVersion
		[Optional] Use this when updating animations or attempting to overwrite other animations, highest version number will prevail (matching version numbers is first come-first serve)
	AnimName
		[Optional] Name for the animation
	AnimAuthor
		[Optional] Credit name of the animation creator
	AnimByPath
		[Required] AnimByPath sections ask for the 'Game Path' to the Aniamtion Montage you've packaged in UE5, format the value name (the first part) to be the character slot that should stay consistent through-out the metadata, then the second part should be the path to the animation in the format /Game/Mods/YourModName/AnimMonAssetName excluding any file types or additionl quotes. You can also reference other animations from different packs as long as the file-path lines up. (Even in-game animations work, however they may not playback how you'd expect.)
	NotErotic
		NonErotic while false will make the animation erotic and trigger sexual effects. When true the animaiton is Not Erotic and will not trigger sexual effects. (Use true when making non-sex related animations like petting, or interaction animations)
	IsLooping
		Toggles whether your animation should loop or not, make sure the actual animation montage loops as well or else it my just play through once and just stop, making for some awkward situations. (When true, animation is expected to loop, if false it will only play through once, useful for transition and climax animations.)
	Aggressors
		[Optional] List of aggressors in the animation, if no aggressors or all are marked as aggressive then the animation is consentual, otherwise will be considered aggressive with non-aggressors as victims.
	Tags
		[Optional] Tags you wish to add to the animation for easier sorting and to assist automated systems properly apply effects. Enter tags for both the main animaiton and the potential climax animation. Some basic tags like position, sexual orientation, climax location, ect are recommended. (We'll try and build a tag list in the future to help with this)
	SpeedDefault
		[Optional] SpeedDefault defines how 'quickly' the animation should play for each slot in order (0,1,2,3...), if your animation is not a looping animation then non-matching speeds could cause some slots to finish their animation 'too early' and cause strangeness. Useful if you have a looping animation with multiple actors but want to adjust the playback speed in your event without making a new animation. Default speed is 1.0
	StartTime
		[Optional] At what point, defined in seconds, we should start the animation at. Useful if you want to adjust how the animation transitions without making a new animation or want to start a looping animation in the middle of the loop rather than the start.
	EndTime
		[Optional] At what point, defined in seconds, we should end the animation. if non-zero for non-looping animations the animation player will try and stop this animation at this point (starts blend-out here), for looping animations the animation player will try to only transition at this point in the animation.
	SyncPosition
		[Optional] While true, SyncPosition will attempt to use a sockets system to keep characters aligned rather than a univeral world point. Generally leave this disabled unless the animation is specifically designed for this functionality.
	ActTypes
		[Recommended] Defines the 'type' of sexual act each character is currently in. You can define multiple acts for each slot. This is used internally to trigger different sexual effects, tags can also be used for automatic detection but it's best to define these so you know things will function properly.
			ActType : None/NonErotic/Masturbation/Penetrating/Penetrated/Handling/External/Foreplay/Spectating
			ActLocation : None/Vaginal/Anal/Oral/Breasts/Body/Feet/Distant
	Compatibility
		[Required] Compatibility defines what combination of characters the animation will work for, if the combination isn't set in this list then the animation may not play even if the given characters are compatible. You can set up multiple compatibility sets if your animation is compatible with multiple characters/combinations.
			SexEquip : None/Female/Male/Futa/FullFuta/Neutered/FullNeutered
				SexEquip referse to 'sexual equipment' such as a vagina, penis, breasts, ect. The first value should be the slot the requirement applies to, with the second being the requirement (use None if no sexual equipment is required). To prevent having to register multiple compatibility arrays for different sex gender combinations, use the setting that includes the least requirements, for example if a 'futa' animation only involves the penis, set male as the gender so it will be compatible for all characters that use a penis but doesn't require breasts for playback. (None=No Requirement, Female=Breasts + Vagina, Male=Penis, Futa=Penis + Breasts, FullFuta=Vagina + Breasts + Penis, Neutered=Breasts Only, FullNeutered=No Sexual Equipment.
			ByID
				ByID references is asking for the in-game characterID, use the modding wiki to get these values for pals, use 'Human' for all human characters (More complex systems may be added in the future). First value is the slot, other value should be the ID.
			ByName
				ByName references use the typical in-game display name to try and find the associated ID, may not always work and will be inconsistent so using this value is not recommended. Useful if a character has special definitions/exceptions defined by SCake.
			MyMeshRef
				ByMesh references directly references the mesh/skeleton path used by the character, does not always work and isn't compatible with all mods. Useful if a unique model is used for some variants but not others and animations are unique between them.
			PalSize
				PalSize is a scaling factor used by the game to re-size pals for different variants. You can define size in compatibility to specifically check for the defined size and not allow other sizes to play the animation. If nothing is entered then Size is not checked, 'None' is an actual size defined by the game and may restrict animations. Only use this set if you know what you're doing!
	LinkClimaxAnims
		[Recommended] LinkClimaxAnims defines the linked climax variants for the animation by slot, if these are not defined properly then the climax animation may not play properly.
			SlotsToClimax : Inside/Outside
				SlotsToClimax defines each slot expected to climax with the associated value being where they climax, either Inside/Outside. If set to none or left blank, the animation handler may try to use tags to 'guess' where the climax happens.
			IsLooping
				Climax animations define their looping status indepentant of the animation and defaults to false.
	ActorAdjust
		[Optional] Defines the offset for the referenced character relative to the animation's root location. Use this value to make smaller adjustments to where characters should be position in animaitons and fix alignment issues caused by having different models than the original animation. Size values are ignored in transform parameters.
			TransformAllOffset
				Sets the offset for the character regardless of size definition.
			TransformBySize
				Sets the offset for the specified size variant.
	ObjectTarget
		[Optional] Defines allowed objects and their offset when using furniture/object animations. Exclude this section if no objects are used. Multiple objects can be defined for general animations, Tags may also be used to try and automatically set object targets.
			ObjectByRef
				ByClassName references refer to the in-game reference name returned when checking the class, only use these references if you know what you're doing.
			ObjectByClassName
				Defines objects by a given ID, not all objects return any ID and methods may change between them. Only use this value if you know what you're doing.
			ObjectByID
				Transform defines the offset for the entire animation related to the defined object. This value moves all participants, use the actor adjust parameters to adjust individual slots.
	EquipType
		[Optional] Defines an object for the specified slot to equip, think like a sex toy or something similar (could also be used for non-erotic stuff honestly, I'm just a degenerate).
			EquipLocation
				Defines what 'slot' to place the object in, use either a bone/socket slot name or a preset from SCake.
			Scale
				Although scale can be set, it may not behave as expected in-game. Don't forget to test!
	ArbString
		[Optional] ArbString allows arbitrary data to be added with an animation in the format 'name' - 'string'. Arbitrary data can be accessed by modules, using this section you can add additioanl data and information for those mods.
	
	~ Parameters for Animation Events ~
	
	UniqueEventID
		[Required] UniqueID for the Event
	EventVersion
		[Optional] Acts just like AnimVersion, but for events instead
	EventName
		Name for the Animation Event
	EventAuthor
		Name of the Animation Event creator
	Addtags
		[Optional]  Tags from the included animations in the event are already added, Addtags allows you to define extra tags to use on-top of those. You don't need to add any redundant tags (duplicate tags are removed when registering animations).
	Stages
		[Required] Stages refer to each 'part' of an Event, stages progress either linearly or how they are defined in Stage Order. Think of this as how an animation will progress through individual animations. An event can feature any mixture of animations and will automatically define parameters based on those animations. The order these are registered in matters, so define them in-order with incrementing numbers for each set starting at 0 (0, 1, 2, 3...)
			StageName
				Name for this stage
			AnimID
				This is the UniqueAnimID for the animation you wish to play in this stage. If this value is invalid or not defined then stages won't register properly and the event may even fail to register completely
			SpeedMod
				SpeedMod alters the speed of this stage's animation. Useful if you want to make a speed variant of an animation without registering another animation.
			DurationWeight
				If the animation is looping, DurationWeight sets how much of the expected animation time this stage should take. The default is 1.0, increase to take more time, decrease to take less time.
			ClimaxVar
				Sets an override for the climax animimation or allows additional animations to be added. Useful if you want to add more climax animations to an event or create more interesting combinations/variants.
					SlotsToClimax : Inside/Outside
						SlotsToClimax slots are required, however the climax location is only used if the animation lacks a definition for it.
	StageOrder
		[Optional] StageOrder defines what order stages should play in, if left blank then stages will just play linearly (0, 1, 2, 3...). Useful if you'd like to change the order or define a stage to play multiple times, like going from stage 1 to 2 then back to 1.
	OverwriteClimax
		When true, the GlobalClimaxVar will overwrite all climax animations, otherwise only use GlobalClimaxVar if no climax animation of that type is defined.
	GlobalClimaxVar
		[Recommended] Defines climax animations to use through-out the full animation. By default (OverwriteClimax=false) these animations will only play if no climax animation is already defined by either the animation or in the stage.
	HasPostClimax
		While true, the animation will try to play the defined animation after the Post Climax Requirements are met. (Effectively plays at the end of an animation event)
	PostClimaxReq
		[Optional] Defines a custom requirement for the post climax animation to play, otherwise it won't try to play the animation. Recommended to leave at 0 to respect default settings behavior unless the animation specifically expects very specific climaxed characters.
	PostClimaxStage
		[Optional] Defines a Stage to play as the post-climax stage. Use in combination with StageOrder to exclude this animation from normal play if you don't want it to repeat another animation.
	UniqueDuration
		[Optional] Defines a hard-set duration for this animation event that can not be exceeded. Use this value if the animation has very specific interaction requirements and isn't used as a general scene.
	
	~ Parameters for Stages ~
	
	StageName
		Name to give this stage
	AnimID
		Gets animation to play by the UniqueAnimID you set
	ClimaxVar
		[Optional] List of climax variant animations to override an animation's linked climax variants
	SpeedMod
		[Optional] Alters the animation playback speed
	DurationWeight
		[Optional] How much of the total time this animation should attempt to take up before the final climax animations, adjusts based on a percentage, non-looping animations ignore this setting
	StartTime
		[Optional] Start time for the animations when it begins playing
	EndTime
		[Optional] End time for the animations before it transitions to the next animation

	~ Parameters for Climax Links ~

	SlotsToClimax
		Slots expected to climax with this animation and where they should climax
	AnimByPath
		Slots and their associated animation paths
	IsLooping
		Whether the animation should be looping or not

	~ Parameters for Climax Vars ~

	SlotsToClimax
		Slots expected to climax with this animation and where they should climax
	AnimID
		The ID for the animation to play

	~ Climax Types ~
	
	Default
		Uses preset behavior for the selected ActType
	Inside
		Climax while penetrating inside with changed behavior based on ActType
	Outside
		Climax while not penetrating with changed behavior based on ActType

	~ Act Type ~
	None
		Uses other data to 'guess' on the act type, such as tags or act location and genders
	NonErotic
	Masturbation
	Penetrating
	Penetrated
	Handling
	External
	Foreplay
	Spectating
	
	~ Act Location ~
	None
		Uses other data to 'guess' on the act location, such as tags or act type and gender
	Vaginal
	Anal
	Oral
	Breasts
	Body
	Feet
	Distant
	
	~ SexEquipReq ~
	None
	Female
	Male
	Futa
	FullFuta
	Neutered
	FullNeutered

	~ PalSize ~
	None
	XS
	S
	M
	L
	XL